---
menu: Non-active Proposals
name: Checkbox (Explainer)

pathToResearch: /components/checkbox.research
layout: ../../layouts/ComponentLayout.astro
---

import CheckboxAnatomy from '../../components/checkbox-anatomy'

## Overview

The `<checkbox>` element is a control that allows the user to select a binary "checked" state, either checked or unchecked. The `<checkbox>` also supports a second binary "indeterminate" state.

### Use Cases

The `<checkbox>` control is primarily leveraged to indicate a binary state. For example, many forms use a checkbox to indicate that a user has accepted _terms of service_ or to opt in or out of email communcations.

## Prior Art/Examples

- [Checkbox input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox)
- [KoliBri](https://public-ui.github.io/docs/components/input-checkbox)
- [WAI-ARIA Checkbox](https://www.w3.org/TR/wai-aria-practices/#checkbox)
- [WHATWG](<https://html.spec.whatwg.org/multipage/input.html#checkbox-state-(type=checkbox)>)

## Design

### API

#### Properties

| Attribute Name   | Type     | Default Value | Description                                                                                           |
| ---------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `checked`        | `bool`   | `false`       | Controls whether the checkbox is checked or unchecked.                                                |
| `indeterminate`  | `bool`   | `false`       | Controls whether the checkbox has a determinable state.                                               |
| `defaultChecked` | `bool`   | `false`       | The initial value for `checked`. Defaults to false.                                                   |
| `value`          | `string` | `"on"`        | The value of the checkbox.                                                                            |
| `autofocus`      | `bool`   | `false`       | Get focus by default.                                                                                 |
| `disabled`       | `bool`   | `false`       | Prevents the user from interacting with the control. Defaults to false.                               |
| `form`           | `string` | `null`        | Associates the element with a form in the document whose `id` is this value.                          |
| `name`           | `string` | `""`          | Specify the name of the control for purposes of form submission.                                      |
| `required`       | `bool`   | `false`       | Indicates that the checkbox is invalid unless checked.                                                |
| `readonly`       | `bool`   | `readonly`    | Indicates that the checkbox is not interactive but its value should still be submitted with the form. |

#### Events

| Event Name | Detail Type | Bubbles | Composed | Cancellable | Dispatch Behavior                                          |
| ---------- | ----------- | ------- | -------- | ----------- | ---------------------------------------------------------- |
| `change`   | none        | `true`  | `true`   | `false`     | Fired when the checkbox's `value` is committed by the user. |
| `input`    | none        | `true`  | `true`   | `false`     | Fired when the checkbox's `value` changes.                 |

### Anatomy

<CheckboxAnatomy />

#### DOM Structure

```html
<oui-checkbox>
  <label part="label">
    <slot name="label"></slot>
  </label>
  <div part="indicator">
    <slot name="indicator"></slot>
  </div>
</oui-checkbox>
```

#### Slots

| Slot Name   | Description                                                             | Fallback Content                                  |
| ----------- | ----------------------------------------------------------------------- | ------------------------------------------------- |
| `label`     | Add custom markup for the control's label                               | Empty                                             |
| `indicator` | Content to indicate the checkbox is in a checked or indeterminate state | Element with checked and indeterminate indicators |

#### CSS Parts

| Slot Name   | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| `label`     | The control's label                                           |
| `indicator` | Indicates the checkbox is in a checked or indeterminate state |

## Behavior

### Accessibility

#### States and Interactions

| State Group     | States         | Initial State | Description                                                                                                                                 | Interaction/Transition                       |
| --------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `checked`       | `true`/`false` | `false`       | When `true`, associates the control with the parent form data and displays the control with a checked appearance if not also indeterminate. | User click. Controlled programmatically.     |
| `indeterminate` | `true`/`false` | `false`       | When `true`, displays the control with an indeterminate appearance.                                                                         | No interaction. Controlled programmatically. |
| `disabled`      | `true`/`false` | `false`       | When `true`, disables the control, preventing user interaction and displaying the control with a disabled appearance.                       | No interaction. Controlled programmatically. |
| `readonly`      | `true`/`false` | `false`       | When `true`, the control's checked value cannot be changed by user interaction.                                                             | No interaction. Controlled programmatically. |

#### Keyboard

Keyboard users can operate the `<checkbox>` as follows:

- `<checkbox>` is eligible for document focus.
- `<checkbox>` is eligible for `autofocus` when the `autofocus` attribute is present on the host.
- `<checkbox>` can be the target of `click` events (when not `disabled`) either through mouse click, user tap, or keyboard `space` key press.

#### Form input

Control is eligible for all native from capabilities including:

- Form submission
- Form validation
- Form state restoration

### Use with Assistive Technology

Implements the [checkbox role](https://www.w3.org/TR/wai-aria-1.1/#checkbox) per the
[HTML AAM spec](https://www.w3.org/TR/html-aam-1.0/#html-element-role-mappings).
